Inside Macintosh: QuickTime Components
Sequence grabber channel components must provide a full set of functions that allow the sequence grabber component to control the preview or record operation. The sequence grabber component can use these functions to start and stop the operation, to pause data collection, and to write captured data to a movie. This section describes these functions.
The sequence grabber component uses the SGStartPreview function to start a preview operation. The SGStartRecord function starts a record operation. The SGStop function stops your channel component after a preview or record operation.
The sequence grabber component grants processing time to your channel component by calling the SGIdle function. The sequence grabber notifies you of update events by calling your SGUpdate function.
The sequence grabber pauses the current operation by calling the SGPause function.
The sequence grabber component calls your SGWriteSamples function to write captured data to a movie file after a record operation.
The sequence grabber component prepares your channel component for an upcoming preview or record operation by calling the SGPrepare function. This function also allows the sequence grabber component to verify that your component can support the parameters an application has specified. The SGRelease function releases system resources allocated during the SGPrepare function.
The SGStartPreview function instructs your channel to begin processing its source data. In preview mode, your component does not save any of the data it gathers from its source.
pascal ComponentResult SGStartPreview (SeqGrabComponent s);
Your channel component should immediately present the data to the user in the appropriate format, according to your channel's configuration (see "Configuration Functions for All Channel Components," which begins on Configuration Functions for All Channel Components , for information about functions that configure channels). Display video data in the destination display region; play sound data at the specified volume settings.
The sequence grabber component stops the preview process by calling your SGStop function, which is described on SGStop .
The SGStartRecord function instructs your channel component to begin recording data from its source. The sequence grabber component stores the collected data according to the recording parameters that the calling application specified with the sequence grabber component's SGSetDataOutput function (described in the chapter "Sequence Grabber Components" in this book). Your channel component should immediately begin recording data in the appropriate format, according to your channel's configuration (see "Configuration Functions for All Channel Components," which begins on Configuration Functions for All Channel Components , for information about functions that configure channels).
pascal ComponentResult SGStartRecord (SeqGrabComponent s);
The sequence grabber component can switch from previewing to recording by calling this function during a preview operation--the sequence grabber need not stop the preview operation first.
The sequence grabber component stops the recording process by calling your SGStop function, which is described on SGStop .
The SGIdle function provides processing time to your channel component.
pascal ComponentResult SGIdle (SeqGrabComponent s);
After starting a preview or record operation, the application calls the sequence grabber component's SGIdle function as often as possible. The sequence grabber component then calls your SGIdle function. This continues until the calling application stops the operation by calling the SGStop sequence grabber function.
Your SGIdle function reports several status and error conditions by means of its result code. If your component returns a nonzero result code during a record operation, the application should still call the SGStop function (described on SGStop ) so that the sequence grabber component can store the data it has collected.
The SGUpdate function allows you to learn about update events. This gives you an opportunity to update your display.
pascal ComponentResult SGUpdate (SeqGrabComponent s,
RgnHandle updateRgn);
SGUpdate (theSG, ((WindowPeek)updateWindow)->updateRgn);
Applications call the sequence grabber's SGUpdate function whenever they receive an update event for a window that contains a sequence grabber display. The sequence grabber then calls each affected channel. Applications should call this function before calling the Window Manager's BeginUpdate function.
The SGStop function stops a preview or record operation.
pascal ComponentResult SGStop (SeqGrabComponent s);
In the case of a record operation, the sequence grabber component stores the collected movie data in the assigned movie file. The sequence grabber component then calls your SGWriteSamples function (described in the next section) to place the references to the captured data into the movie after it calls SGStop .
Warning
It is dangerous to allow an update event to occur during recording. Many digitizers capture directly to the screen, and an update event will result in data loss.
The sequence grabber component calls the SGWriteSamples function when it is ready to add recorded data to a movie.
pascal ComponentResult SGWriteSamples (SGChannel c, Movie m,
AliasHandle theFile);
The sequence grabber component calls this function when the recording operation is complete, after calling your SGStop function (described on SGStop ). In this manner, your channel component can avoid unnecessary Movie Toolbox overhead during the record operation.
A sequence grabber component can suspend or restart a record or preview operation by calling the SGPause function.
pascal ComponentResult SGPause (SeqGrabComponent s, Byte pause);
The sequence grabber component supplies a constant value in the paused parameter that instructs your component to pause or restart the current operation.
The SGPrepare function instructs your component to get ready to begin a preview or record operation (or both)--the sequence grabber component specifies the operations.
pascal ComponentResult SGPrepare (SeqGrabComponent s,
Boolean prepareForPreview,
Boolean prepareForRecord);
Your component should do whatever is necessary to get ready to start the operation. The goal is to reduce the delay between the time when the sequence grabber calls your SGStartPreview function (described on SGStartPreview ) or SGStartRecord function (described on SGStartRecord ) and the time when the operation actually begins. This may involve allocating memory or readying special hardware.
The SGRelease function instructs your component to release any system resources it allocated during the SGPrepare function, which is described in the previous section.
pascal ComponentResult SGRelease (SeqGrabComponent s);